feat: 增加事务化文件系统复制能力 - #4185

变更说明

新增文件与目录复制能力，覆盖 VikingFS、HTTP API 和 ov CLI。复制时同步迁移已有向量记录，避免重复解析、文件级 VLM 和 embedding；提交后异步重建受影响父目录的语义信息。

人工参与

• 有人工参与实现或评审过程
• 本 PR 完全由 AI Agent 生成，没有人工参与

关联事项

接口提案已经在项目 Discussion 中批准。

变更类型

• Bug 修复（不破坏现有功能）
• 新功能（不破坏现有功能）
• 破坏性变更
• 文档更新
• 重构（无独立功能变化）
• 性能优化
• 测试更新

主要改动

cp 能力

新增 POST /api/v1/fs/cp 和 ov cp：

• ov cp 支持单文件复制，ov cp -r 支持目录递归复制。
• 目标父目录必须存在，目标路径不能已存在。
• 同步复制文件内容及对应向量，保留源数据。
• 递归复制逐项校验权限，并排除 watch 控制文件。

RAGFS 原子发布与失败补偿

AGFS 复制已下沉到 RAGFS：

• RAGFS 统一持有源路径、目标路径和 staging 路径锁。
• 数据先完整复制到目标目录下的隐藏 staging 路径，成功后通过一次 rename 发布到最终目标；失败时清理 staging，避免暴露半成品目标。对象存储后端仍遵循其原生 best-effort rename 语义。
• VikingFS 在 AGFS 发布成功后复制已有向量并改写 URI，不重新生成 embedding。
• 向量复制失败时清理已写入的目标向量和目标 AGFS 数据；补偿失败会返回失败阶段及残留 URI，便于人工修复。
• mv 继续采用“复制目标 → 迁移向量 → 删除源”的补偿式流程。

这里不是跨 AGFS 与 VectorDB 的强一致两阶段提交：AGFS 内部通过 staging 原子发布，跨存储一致性通过严格校验和补偿回滚保证。

父目录语义刷新

cp 完成后异步刷新目标父目录；mv 完成后异步刷新源、目标父目录。刷新消息使用 generation_trigger="content_copy"：

• 根据变更后的目录独立采样，默认最多 32 项。
• 只读取已有文件 L2 摘要和子目录 abstract，不重新解析文件，也不生成缺失的 L2 摘要。
• 调用目录级 VLM 生成 overview，并从新 overview 提取 abstract。
• 只刷新直接父目录，不继续向祖先冒泡。

接口只等待消息入队，不等待语义处理完成。

文档

补充中英文 HTTP 接口、端点总览和 CLI 使用文档。

局限性

当前没有提供 AGFS 与 VectorDB 的强一致快照。如果 add-resource 已完成 AGFS 落盘，但向量仍在生成，cp 可能只复制当时已经写入的向量，导致目标向量不完整。

正常情况下，add-resource 在语义和 embedding 阶段持有目录 Tree Lock，重叠的 cp 通常会返回 409 path_busy，实际竞态窗口较短，本期暂不增加索引完成屏障或增量补齐机制。

父目录语义刷新是异步的，cp/mv 返回成功时，新的 overview 和 abstract 可能尚未生成。

测试

• 已增加测试验证功能行为
• 新增及相关测试在本地通过
• 已在 macOS 验证

本次 rebase 后的定向验证：

• 80 个相关 Python 测试通过。
• 11 个 RAGFS copy 测试通过。
• Rust ov_cli 的 cp 请求测试通过。
• cargo check -p ragfs-python 通过。
• 改动文件通过 Ruff lint、format、Python compile 和 diff 检查。
• 已通过本地服务手工验证 HTTP 接口和 ov cp 命令。

全量 filesystem router 测试仍有一个 upstream/main 已存在的 attrs Filter DSL 用例失败，与本 PR 无关；本机 ragfs-python 单元测试链接阶段缺少 Python 符号，但 cargo check 已通过。

检查清单

• 代码符合项目风格
• 已完成自查
• 已为难以理解的逻辑补充注释
• 已补充对应文档
• 未引入新的依赖